<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html><head><title>Programming in Lua : 24.2.2</title>
<link rel="stylesheet" type="text/css" href="pil.css">
</head>
<body>
<p class="warning">
<A HREF="contents.html"><IMG TITLE="Programming in Lua (first edition)" SRC="capa.jpg" ALT="" ALIGN="left"></A>This first edition was written for Lua 5.0. While still largely relevant for later versions, there are some differences.<BR>The third edition targets Lua 5.2 and is available at <A HREF="http://www.amazon.com/exec/obidos/ASIN/859037985X/theprogrammil3-20">Amazon</A> and other bookstores.<BR>By buying the book, you also help to <A HREF="../donations.html">support the Lua project</A>.
</p>
<table width="100%" class="nav">
<tr>
<td width="10%" align="left"><a href="24.2.1.html"><img border="0" src="left.png" alt="Previous"></a></td>
<td width="80%" align="center"><a href="contents.html"><font face="Helvetica,Arial,sanserif">
<font color="gray">Programming in </font><font color="blue"> Lua</font>
</font></a></td>
<td width="10%" align="right"><a href="24.2.3.html"><img border="0" src="right.png" alt="Next"></a></td>
</tr>
<tr>
<td width="10%" align="left"></td>
<td width="80%" align="center"><a href="contents.html#P4">Part IV. The C API</a>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
<a href="contents.html#24">Chapter 24. An Overview of the C API</a></td>
<td width="10%" align="right"></td></tr>
</table>
<hr/>
<p><h3>24.2.2 &ndash; Querying Elements</h3>

<p>To refer to elements in the stack,
the API uses <em>indices</em>.
The first element in the stack
(that is, the element that was pushed first) has index 1,
the next one has index 2, and so on.
We can also access elements using the
top of the stack as our reference,
using negative indices.
In that case, <em>-1</em> refers to the element at the top
(that is, the last element pushed),
<em>-2</em> to the previous element, and so on.
For instance, the call <code>lua_tostring(L, -1)</code> returns
the value at the top of the stack as a string.
As we will see,
there are several occasions when it is natural to index
the stack from the bottom (that is, with positive indices)
and several other occasions when the natural way is to use
negative indices.

<p>To check whether an element has a specific type,
the API offers a family of functions <code>lua_is*</code>,
where the <code>*</code> can be any Lua type.
So, there are
<code>lua_isnumber</code>, <code>lua_isstring</code>, <code>lua_istable</code>, and the like.
All these functions have the same prototype:
<pre>
    int lua_is... (lua_State *L, int index);
</pre>
The <code>lua_isnumber</code> and <code>lua_isstring</code> functions do not
check whether the value has that specific type,
but whether the value can be converted to that type.
For instance, any number satisfies <code>lua_isstring</code>.

<p>There is also a function <code>lua_type</code>,
which returns the type of an element in the stack.
(Some of the <code>lua_is*</code> functions are actually macros
that use this function.)
Each type is represented by a constant
defined in the header file <code>lua.h</code>:
<code>LUA_TNIL</code>,
<code>LUA_TBOOLEAN</code>,
<code>LUA_TNUMBER</code>,
<code>LUA_TSTRING</code>,
<code>LUA_TTABLE</code>,
<code>LUA_TFUNCTION</code>,
<code>LUA_TUSERDATA</code>,
and <code>LUA_TTHREAD</code>.
This function is mainly used in conjunction with a switch statement.
It is also useful when we need to check for strings and
numbers without coercions.

<p>To get a value from the stack,
there are the <code>lua_to*</code> functions:
<pre>
    int            lua_toboolean (lua_State *L, int index);
    double         lua_tonumber (lua_State *L, int index);
    const char    *lua_tostring (lua_State *L, int index);
    size_t         lua_strlen (lua_State *L, int index);
</pre>
It is OK to call them even when the given element does not have
the correct type.
In this case, <code>lua_toboolean</code>, <code>lua_tonumber</code>
and <code>lua_strlen</code> return zero
and the others return <code>NULL</code>.
The zero is not useful,
but ANSI C provides us with no invalid numeric value that we could
use to signal errors.
For the other functions, however,
we frequently do not need to use the corresponding <code>lua_is*</code> function:
We just call <code>lua_to*</code>
and then test whether the result is not <code>NULL</code>.

<p>The <code>lua_tostring</code> function returns a pointer to an internal
copy of the string.
You cannot change it (there is a <code>const</code> there to remind you).
Lua ensures that this pointer is valid as long as the
corresponding value is in the stack.
When a C function returns,
Lua clears its stack;
therefore, as a rule,
you should never store pointers to Lua strings
outside the function that got them.

<p>Any string that <code>lua_tostring</code> returns always has a zero at its end,
but it can have other zeros inside it.
The <code>lua_strlen</code> function returns the correct length of the string.
In particular,
assuming that the value at the top of the stack is a string,
the following assertions are always valid:
<pre>
    const char *s = lua_tostring(L, -1);   /* any Lua string */
    size_t l = lua_strlen(L, -1);          /* its length */
    assert(s[l] == '\0');
    assert(strlen(s) &lt;= l);
</pre>

<hr/>
<table width="100%" class="nav">
<tr valign="top">
<td width="90%" align="left">
<small>
  Copyright &copy; 2003&ndash;2004 Roberto Ierusalimschy.  All rights reserved.
</small>
</td>
<td width="10%" align="right"><a href="24.2.3.html"><img border="0" src="right.png" alt="Next"></a></td>
</tr>
</table>


</body></html>

